home *** CD-ROM | disk | FTP | other *** search
/ Aminet 24 / Aminet 24 (1998)(GTI - Schatztruhe)[!][Apr 1998].iso / Aminet / dev / c / cxref_1_4a.lha / FAQ < prev    next >
Text File  |  1997-06-22  |  18KB  |  463 lines
  1.           CXREF VERSION 1.4 - FREQUENTLY ASKED QUESTIONS AND ANSWERS
  2.           ==========================================================
  3.  
  4. This file contains a list of frequently asked questions and their answers
  5. relating to cxref version 1.4.
  6.  
  7. Not all of the questions here are real users questions, some of them have been
  8. made up to give some help to people trying to use the program who find that the
  9. README documentation is insufficient.
  10.  
  11. --------------------------------------------------------------------------------
  12.  
  13. Section 0 - Why doesn't this FAQ answer my question?
  14.  
  15. --------------------
  16.  
  17. Section 1 - What does cxref do (and what it doesn't)
  18.  
  19. Q 1.1   Does cxref support C++?
  20. Q 1.2   Does cxref show which #includes that are not needed?
  21. Q 1.3   Can cxref document automatic function variables?
  22. Q 1.4   Does cxref run on systems other than UNIX?
  23.  
  24. --------------------
  25.  
  26. Section 2 - When cxref does not work
  27.  
  28. Q 2.1a  How do I find out what is causing the parse error?
  29. Q 2.1b  What does this parse error message mean?
  30. Q 2.2   Where are files doc/cxref.html & FAQ.html referenced from README.html?
  31. Q 2.3   Why are half of the cross references missing?
  32. Q 2.4   Why can't cxref process my header file in isolation?
  33. Q 2.5   Why can't LaTeX process the output files?
  34. Q 2.6   Why does the include file name have the complete path name?
  35.  
  36. --------------------
  37.  
  38. Section 3 - How to make cxref do what you want
  39.  
  40. Q 3.1   How do I use cxref to process source files in more than one directory?
  41. Q 3.2   How can I add my own information to the output files?
  42. Q 3.3   Can I get a subset of the cross-reference information?
  43. Q 3.4   Is there an easy way to generate the comments in the correct format?
  44. Q 3.5   How do I produce LaTeX output from a single source.c.tex output file?
  45. Q 3.6   How can I pass extra arguments to the C pre-processor?
  46. Q 3.7   Can I cross-reference my source code at the same time as compiling it?
  47. Q 3.8   What use is the .cxref configuration file?
  48.  
  49. --------------------
  50.  
  51. Section 4 - More information about cxref
  52.  
  53. Q 4.1   Who wrote cxref, When and Why?
  54. Q 4.2   How do I report bugs in cxref?
  55.  
  56. --------------------------------------------------------------------------------
  57.  
  58. Section 0 - Why doesn't this FAQ answer my question?
  59.  
  60. This FAQ is released with each new version of the cxref program, so if the
  61. question is one that is frequently asked about the new version then you will by
  62. definition not find the answer here.
  63.  
  64. You can find the latest information about cxref at the cxref web-page, this
  65. contains among other things a list of bug-fixes for the latest version.
  66.  
  67. http://www.gedanken.demon.co.uk/cxref/
  68.  
  69. --------------------------------------------------------------------------------
  70.  
  71. Section 1 - What does cxref do (and what it doesn't)
  72.  
  73. --------------------
  74.  
  75. Q 1.1   Does cxref support C++?
  76.  
  77. No.
  78.  
  79. The cxref program only works for C, More specifically:
  80.  
  81. 1) ANSI standard C with some leniency for common non-ANSI syntax.
  82.         For example, the construct 'switch(foo) { case 1: ... default: }' is not
  83.         ANSI, there must be a ';' after the default label, but it is accepted by
  84.         cxref.
  85.  
  86. 2) Traditional (K&R) function declarations, with implicit 'int' and 'void'.
  87.         For example 'foo(){}' is parsed as if 'int foo(void){}' was specified.
  88.  
  89. 3) The ability to parse GCC extensions.
  90.         The GCC '__attribute__' and '__extension__' keywords and most of the
  91.         other GCC extensions. The 'inline' keyword is allowed.
  92.  
  93. --------------------
  94.  
  95. Q 1.2   Does cxref show which #includes that are not needed?
  96.  
  97. No.
  98.  
  99. The output of the cxref program cross-references all of the functions,
  100. variables, type definitions, included file etc.  There is not a way of
  101. identifying files that are included in another source file that do not need to
  102. be.
  103.  
  104. --------------------
  105.  
  106. Q 1.3   Can cxref document automatic function variables?
  107.  
  108. No.
  109.  
  110. The inclusion of automatic variables in the output is not included.  This is
  111. because of the number of them in a typical function.  In theory it could be made
  112. to do this.
  113.  
  114. --------------------
  115.  
  116. Q 1.4   Does cxref run on systems other than UNIX?
  117.  
  118. For example DOS / Win3 / Win95 / WinNT / OS/2.
  119.  
  120. UNIX    = Yes
  121.         This is the system that the program way designed and initially written
  122.         for, it should work on many versions of UNIX.
  123.         I know that it works on Linux, SunOS 4.1.x, Solaris 2.x, AIX & HP-UX 10.
  124.  
  125. DOS/Win3 = No
  126.         The program was not designed for DOS, the filenames used and the
  127.         multi-process nature of the program do not allow this.
  128.  
  129. Win95/WinNT = Maybe
  130.         Since Windows 95 and Windows NT claim to be real 32-bit multi-tasking
  131.         operating systems, and support the long filenames that are required, it
  132.         should in theory be possible to get the program working on these.
  133.         I have reports that it is possible, but I do not support cxref for these
  134.         OSes.
  135.  
  136. OS/2    = Maybe
  137.         As for Windows 95 / Windows NT above.
  138.         I have reports that it is possible with OS/2 Warp with emx, but I do not
  139.         support cxref for this OS.
  140.  
  141. --------------------------------------------------------------------------------
  142.  
  143. Section 2 - When cxref does not work
  144.  
  145. --------------------
  146.  
  147. Q 2.1a  How do I find out what is causing the parse error?
  148.  
  149. The following error message is generated by cxref when parsing a source file
  150. (with YYDEBUG set to 0 in parse-yy.h when cxref was compiled).
  151.  
  152. test.c:   4: parse error, expecting `','' or `';''
  153. ^^^^^^  ^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  154. file    line            type of error
  155. name    number        generated by yacc
  156.  
  157. The error is on line 4 of the file test.c.  In this case, the error message that
  158. the yacc parser is generating is of some help, more often the error message is
  159. just 'parse error'.
  160.  
  161. If YYDEBUG was set to 1 in parse-yy.h, then a more detailed error message would
  162. be given (see Q 2.1b).
  163.  
  164.  
  165. Q 2.1b  What does this parse error message mean?
  166.  
  167. The following error message is generated by cxref when parsing a source file
  168. (with YYDEBUG set to 1 in parse-yy.h when cxref was compiled).
  169.  
  170. test.c:   4: parse error, expecting `','' or `';''
  171.  
  172. The previous 10, current and next 10 symbols are:
  173.  -8 | 296 :              INT : int
  174.  -7 | 258 :       IDENTIFIER : foo
  175.  -6 |  40 :                  : (
  176.  -5 | 292 :             VOID : void
  177.  -4 |  41 :                  : )
  178.  -3 | 123 :                  : {
  179.  -2 | 296 :              INT : int
  180.  -1 | 258 :       IDENTIFIER : a
  181.   0 | 296 :              INT : int
  182.   1 | 258 :       IDENTIFIER : b
  183.   2 |  59 :                  : ;
  184.   3 | 125 :                  : }
  185. END OF FILE
  186. ^^^               ^^^^^^^^^^  ^^^^^
  187. symbol              symbol    symbol
  188. number               type     value
  189.  
  190. From this we can reconstruct part of the file test.c, using the previous and
  191. next 10 symbol values from the lexer.
  192.  
  193. int foo(void) { int a   int b; }
  194.                       ^
  195. This is where the parse error occured, after 'int a' and before 'int b;'.
  196. The cause of the error is now clear, there is a ';' missing after the
  197. declaration of the variable a.
  198.  
  199. The cxref program is intended to be used on source files that are known to
  200. compile with a C compiler.  In this case a parse error message should not be
  201. seen except for either non-standard C, (and compiler) or a bug in cxref.
  202.  
  203. --------------------
  204.  
  205. Q 2.2   Where are files doc/cxref.html & FAQ.html referenced from README.html?
  206.  
  207. The README.html file has a reference to the files doc/cxref.html and FAQ.html
  208. these files are only present when 'make docs' has been run to generate the cross
  209. references for the cxref program itself.
  210.  
  211. --------------------
  212.  
  213. Q 2.3   Why are half of the cross references missing?
  214.  
  215. The way that cxref works is that it processes all of the source files for a
  216. program, one at a time and generates a cross reference database.  A second pass
  217. of the program is required to generate all of the cross references from the
  218. database of cross reference information.
  219.  
  220. For this reason, the Makefile for the doc directory of cxref uses 'cxref *.c
  221. -xref -Odoc' for the first pass and 'cxref *.c -xref -Odoc -html -latex' for the
  222. second pass.  The first to build the database, the second to produce the
  223. outputs.
  224.  
  225. The reason that the cross reference